home *** CD-ROM | disk | FTP | other *** search
/ Java Programmer's Toolkit / Java Programmer's Toolkit.iso / gs3.53 / xfonts.doc < prev    next >
Text File  |  1996-01-10  |  7KB  |  165 lines
  1.    Copyright (C) 1993 Aladdin Enterprises.  All rights reserved.
  2.   
  3.   This file is part of Aladdin Ghostscript.
  4.   
  5.   Aladdin Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author
  6.   or distributor accepts any responsibility for the consequences of using it,
  7.   or for whether it serves any particular purpose or works at all, unless he
  8.   or she says so in writing.  Refer to the Aladdin Ghostscript Free Public
  9.   License (the "License") for full details.
  10.   
  11.   Every copy of Aladdin Ghostscript must include a copy of the License,
  12.   normally in a plain ASCII text file named PUBLIC.  The License grants you
  13.   the right to copy, modify and redistribute Aladdin Ghostscript, but only
  14.   under certain conditions described in the License.  Among other things, the
  15.   License requires that the copyright notice and this notice be preserved on
  16.   all copies.
  17.  
  18. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  19.  
  20. This file, xfonts.doc, describes the interface between Ghostscript and the
  21. routines that access externally supplied font and text facilities.
  22.  
  23. For an overview of Ghostscript and a list of the documentation files, see
  24. README.
  25.  
  26. ********
  27. ******** Introduction ********
  28. ********
  29.  
  30. Starting with release 2.6, Ghostscript has the ability to use the
  31. character rasterizer provided by the underlying operating system and
  32. window system; specifically, Adobe Type Manager or a TrueType rasterizer
  33. under MS Windows, and the facilities provided by X Windows.  This ability
  34. augments, but does not replace, Ghostscript's own Type 1 rasterizer:
  35. Ghostscript may still use its own rasterizer for very large characters,
  36. characters that are clipped or transformed in unusual ways, and output to
  37. devices other than the screen.
  38.  
  39. Ghostscript interfaces to these platform facilities through a driver-like
  40. interface called the xfont (external font) interface.  Currently, xfont
  41. implementations are associated directly with device drivers; in a future
  42. release, Ghostscript may separate them, so that (for example) it will be
  43. possible to use the platform rasterizer when writing to a file.
  44.  
  45. Please note that beyond this point, this file is likely to be useful only
  46. to a small number of Ghostscript porters and implementors.
  47.  
  48. ********
  49. ******** Types ********
  50. ********
  51.  
  52. gs_char (defined in gsccode.h)
  53.  
  54.     This type represents a character code that appears in a string.
  55. Currently it is always a single byte, but composite fonts or Unicode may
  56. require it to be wider in the future.
  57.  
  58. gs_glyph (defined in gsccode.h)
  59.  
  60.     This type represents a character name like 'period' or 'epsilon'.
  61. From the xfont implementation's point of view, it is just a handle; when
  62. necessary, Ghostscript provides a gs_proc_glyph_name_t procedure (see next
  63. type) to convert it to a string name.
  64.  
  65. gs_proc_glyph_name_t (defined in gsccode.h)
  66.  
  67.     This type represents a procedure that maps a gs_glyph to its
  68. string name; see the description of char_glyph below.
  69.  
  70. gx_xglyph (defined in gsxfont.h)
  71.  
  72.     This type represents a character or glyph code that can be used
  73. with a specific platform font.  Normally it will be a character code that
  74. the implementation of render_char will turn into a 1-character string and
  75. give to the platform's "display string" operation.
  76.  
  77. gx_xfont_procs (declared in gsxfont.h, defined in gxxfont.h)
  78.  
  79.     This type is the xfont analogue of gx_device_procs, the type of
  80. the procedure record that defines an xfont implementation.
  81.  
  82. gx_xfont (declared in gsxfont.h, defined in gxxfont.h)
  83.  
  84.     This type is the gxfont analogue of gx_device, the type of the
  85. basic structure for an xfont.
  86.  
  87. (encoding_index)
  88.  
  89.     This is not really a type, although it probably should be: it is
  90. an int used to indicate the Encoding used by a font.  Defined values are
  91.     0 = StandardEncoding
  92.     1 = ISOLatin1Encoding
  93.     2 = SymbolEncoding
  94.     3 = DingbatsEncoding
  95.     -1 = other encoding
  96.  
  97. ********
  98. ******** Implementation procedures ********
  99. ********
  100.  
  101. All the procedures that return int results return 0 on success, or an
  102. appropriate negative error code in the case of error conditions.  The
  103. error codes are defined in gserrors.h.  The relevant ones are the same as
  104. for drivers (see drivers.doc for details).
  105.  
  106. As for drivers, if an implementation procedure returns an error, it
  107. should use the return_error macro rather than a simple return statement,
  108. e.g.,
  109.  
  110.     return_error(gs_error_VMerror);
  111.  
  112. This macro is defined in gx.h, which is automatically included by
  113. gdevprn.h but not by gserrors.h.
  114.  
  115. Font-level
  116. ----------
  117.  
  118. gx_xfont *(*lookup_font)(P7(gx_device *dev, const byte *fname, uint len,
  119.   int encoding_index, const gs_uid *puid, const gs_matrix *pmat,
  120.   const gs_memory_procs *mprocs))
  121.  
  122.     Look up a font name, UniqueID, and matrix, and return an xfont, or
  123. NULL if no suitable xfont exists.  Use mprocs to allocate the xfont and
  124. any subsidiary data structures.  The matrix is the FontMatrix concatenated
  125. with the CTM, so (roughly speaking) the font size in pixels is pmat->yy *
  126. 1000 for a normal Type 1 font.
  127.  
  128.     Note that this is the only implementation procedure that does not
  129. take an xfont * as its first argument.  In fact, callers of lookup_font
  130. must use the get_xfont_device driver procedure to get the correct device
  131. to pass as the first argument to lookup_font.
  132.  
  133. gx_xglyph (*char_xglyph)(P5(gx_xfont *xf, gs_char chr, int encoding_index,
  134.   gs_glyph glyph, gs_proc_glyph_name_t glyph_name))
  135.  
  136.     Convert a character name to an xglyph code.  In the case of
  137. glyphshow, chr may be gs_no_char; for an ordinary show operation, if
  138. the character code is invalid, glyph may be gs_no_glyph.
  139.  
  140. int (*char_metrics)(P5(gx_xfont *xf, gx_xglyph xg, int wmode,
  141.   gs_int_point *pwidth, gs_int_rect *pbbox))
  142.  
  143.     Get the metrics for a character.  If the metrics are unavailable,
  144. return 1.
  145.  
  146. int (*render_char)(P7(gx_xfont *xf, gx_xglyph xg, gx_device *target,
  147.   int x, int y, gx_color_index color, int required))
  148.  
  149.     Render a character.  (x,y) corresponds to the character origin.
  150. The target may be any Ghostscript device.  A good implementation will
  151. check whether the target can handle this type of xfont directly (e.g., by
  152. checking the target name), and if so, will render the character directly;
  153. otherwise, it will do what has to be done in the general case, namely, get
  154. a bitmap for the character and use the target's copy_mono operation.  If
  155. required is false, the procedure should return an error if the rendering
  156. operation would be expensive, since in this case Ghostscript has already
  157. cached the bitmap and metrics from a previous call with required=true.
  158. If the operation cannot be done, return 1.
  159.  
  160. int (*release)(P2(gx_xfont *xf, const gs_memory_procs *mprocs))
  161.  
  162.     Release any external resources associated with an xfont.  If
  163. mprocs is not NULL, also free any storage allocated by lookup_font
  164. (including the xfont itself).
  165.